Push alert events from your own system to Flashduty through standard protocols to achieve automated alert noise reduction.
:::tips
Flashduty has already adapted webhook protocols for most common alert systems. For these systems, you should first use the corresponding integration for simplicity. This integration provides a standard HTTP interface that requires your development for adaptation. The advantage is that you can push any alert events you want to handle through On-call.
:::
Steps
In Flashduty
You can obtain an integration push URL through either of the following two methods:
Using Dedicated Integration
When you don’t need to route alert events to different collaboration spaces, this method is preferred as it’s simpler.
Using Shared Integration
When you need to route alert events to different collaboration spaces based on the alert event’s Payload information, this method is preferred.
I. Request Description
Request Method
POST, Content-Type:“application/json”
Request Parameters:
| Field | Required | Type | Description |
|---|
| Content-Type | Yes | string | Fixed value: application/json |
Query Strings:
| Field | Required | Type | Description |
|---|
| integration_key | Yes | string | Integration key for access control. Obtained after adding integration. |
Payload:
| Field | Required | Type | Description |
|---|
| title_rule | Yes | string | Alert title, no more than 512 characters, will be truncated if exceeded. Supports dynamic title generation based on alert content, see Customizing Incidents for generation rules. |
| event_status | Yes | string | Alert status. Enumerated values (case-sensitive): Critical, Warning, Info, Ok. When specified as Ok, it means automatic recovery of the alert. |
| alert_key | No | string | Alert identifier, used to update or automatically recover existing alerts. You can customize this value, but it cannot exceed 255 characters. You can also rely on system auto-generation, this value will be returned in the response. If you’re reporting a recovery event, this value must exist. |
| description | No | string | Alert description, no more than 2048 characters, will be truncated if exceeded. |
| labels | No | map | Alert label collection, key is the label name, value is the label value. 1. Both key and value of labels are string type, case-sensitive. 2. Label key should not exceed 128 characters, following Prometheus label naming conventions. Value should not exceed 2048 characters, will be truncated if exceeded. 3. Maximum of 50 labels. See Label Content Reference in Best Practices. Example: “resource”: “171.26.23.22”, “check”: “api latency > 500ms” |
| images | No | []image | Array of images, used for image display in frontend or Feishu/DingTalk application notifications.The system merged/overwritten based on alt, for the same alt (including empty strings), only one is retained |
image Structure
| Field | Required | Type | Description |
|---|
| alt | No | string | Image alternative text, limit 128 characters, truncated if exceeded. |
| src | Yes | string | Image source, value: http/https URL or image_key returned by Image Upload API. Limit 256 characters, discarded if exceeded |
| href | No | string | Hyperlink reference path, limit 256 characters, truncated if exceeded |
Response
| Field Name | Required | Type | Description |
|---|
| request_id | Yes | string | Request ID for trace tracking |
| error | No | Error | Error description, returned only when an error occurs |
| data | No | Data | Report information |
| Field Name | Required | Type | Description |
|---|
| alert_key | No | string | Alert identifier, can be used to report recovery events. If you specified an alert_key when reporting the event, this value remains unchanged. Otherwise, it’s automatically generated by the system. |
| Field Name | Required | Type | Description |
|---|
| code | Yes | string | Error code, see Code for enumerated values |
| message | No | string | Error description |
| Error Code | HTTP Status | Description |
|---|
| InvalidParameter | 400 | Parameter error |
| InvalidContentType | 400 | Content-Type not supported |
| MethodNotAllowed | 400 | HTTP Method not supported |
| Unauthorized | 401 | Login authentication failed |
| AccessDenied | 403 | Permission authentication failed |
| RequestTooFrequently | 429 | Request too frequent |
| RouteNotFound | 404 | Request Method+Path not matched |
| ResourceNotFound | 400 | Account hasn’t purchased resources, please go to the cost center to place an order |
| NoLicense | 400 | Account has insufficient subscription licenses, please upgrade or purchase subscription in the cost center |
| InternalError | 500 | Internal or unknown error |
II. Request Example
Request:
curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_key}' \
-H 'Content-Type: application/json' \
-d '{
"event_status": "Warning",
"title_rule": "cpu idle low than 20%",
"labels": {
"service": "engine",
"cluster":"nj",
"resource":"es.nj.01",
"check":"cpu.idle<20%",
"metric":"node_cpu_seconds_total"
}
}' -v
{
"request_id": "0ace00116215ab4ca0ec5244b8fc54b0",
"data": {
"alert_key": "9qJ798NJoXS4UMVB5SHsNj"
}
}
{
"request_id": "0ace00116215abc0ba4e52449bd305b0",
"error": {
"code": "InvalidParameter",
"message": "integration_key is not a valid one"
}
}
III. Best Practices
- Send events to Flashduty when alert status changes
- When an alert recovers, send an event with status Ok to close the alert. Otherwise, the alert will remain open. If your alert system doesn’t have recovery events, we recommend manually sending recovery events
- Labels are event descriptions, and label content should be as rich as possible (specified when sending, or generated through enrichment rules), such as:
- Alert source, like host, cluster, check, or metric
- Alert ownership information, like team, owner
- Alert category information, like class (api, db, net)
IV. FAQ
